home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / EDITORS / ZAP / !Zap / Docs / E-Entry < prev    next >
Text File  |  1995-06-19  |  35KB  |  708 lines
  1. *************************************************************************
  2. * >E-Entry    Documents the format of a mode entry point table    *
  3. *************************************************************************
  4.  
  5. The offsets in the entry point table are given names beginning 'e_'. The
  6. E-Library program will define the offsets for you.
  7.  
  8. You must fill in the first 8 entries of this table. The rest of the entries
  9. you may leave as 0 (or more simply, set the table length in the 8th word to
  10. 32 bytes). The idea of the mode table, is that you specify a BASE mode. For
  11. all the entry points (from the 9th onwards) that are off the end of your
  12. table, or that you have left as 0, the base mode will be called instead.
  13.  
  14. Hence, the simplest Zap extension mode would just set the base mode as 0 (ie,
  15. TEXT) and leave the rest as 0. You will then get a clone of the text mode.
  16.  
  17. In general the following register conventions are used:
  18.  
  19.     R2    Current column in characters (see E-Windows)
  20.     R3    Current line in characters (see E-Windows)
  21.     R8    Window block pointer / 0 to change the default config
  22.     R9    File block pointer / 0 to change the default config
  23.     R10    Cursor block pointer
  24.     R11    Your extension mode workspace (private word)
  25.     R12    Zaps workspace (private word)
  26.  
  27. In general the entry points have entry and exit conditions:
  28.  
  29.     \E R0-R10=parameters R11=your workspace
  30.        R12=Zap's workspace R13=FD stack R14=return addr
  31.     \X You must save R1-R11 (unless otherwise mentioned).
  32.        You may corrupt R0 and flags.
  33.        Set V flag and put R0=error block pointer on an error.
  34.  
  35. See the E-ZapCalls file for more details on my entry/exit syntax.
  36.  
  37. All offsets given in the table below must be from the start of the module.
  38. Hence the table is relocatable. Zap finds the start address of your module
  39. via the first table entry (e_module). It uses this and an OS_Module call to
  40. determine the address of your workspace (to pass in R11). All strings should
  41. be 0 terminated.
  42.  
  43. Entry points for arbitrary modes may be called using Zap_CallMode,
  44. Zap_CallGivenMode or Zap_BaseMode. If none of these will do, then use
  45. Zap_ReadMode to find the table entry linked points and the address of the
  46. mode's workspace and the entry point can be called directly.
  47.  
  48. Each mode has a word of workspace reserved in the window block (pointed to
  49. by R8) for each file. A mode is responsible for storing the current options
  50. in their mode word when the user changes mode (see e_start/e_end). There
  51. are Zap calls provided to make this easier for you. If you need more than
  52. one word of workspace then the mode word can store the pointer to a block of
  53. workspace if you set a flag in e_mode. See E-Windows (w_mode0...) and E-Vars
  54. (opt_mode0...).
  55.  
  56. The entry points
  57. ================
  58.  
  59. e_module
  60. This gives the table offset from the module start so that the module start
  61. may be calculated by Zap. Ie, module start = address of table start - this
  62. offset.
  63.  
  64. e_title
  65. Offset of the mode title string to be used in the 'Mode' menu. (Ie, the
  66. name of the mode). It should be at most 7 chars long. (eg 'BASIC')
  67.  
  68. e_author
  69. Offset of the author name string (eg 'Dominic Symes').
  70.  
  71. e_basemode
  72. Gives the mode number on which to base null entry points. This is a bit out
  73. of date since modes are now referred to by names and assigned numbers when
  74. loaded. For all practical purposes this will always be 0 (text mode) though
  75. you can use any mode permanently installed in Zap (ie 0=Text 1=byte 2=word
  76. 3=ascii 4=hex 11=throwback).
  77.  
  78. e_mode
  79. Gives the mode number you would like to be in bits b0-b7. Bits 8-31
  80. contain flags. It is VERY important that you do not assume you get this mode
  81. number. Now that Zap loads modes on the fly, modes are often loaded in a
  82. funny order and you cannot guarantee this mode number will be free. I suggest
  83. that (seeing as modes 0-12 already have a standard meaning) you set this to
  84. 13 and then Zap will assign you the next free mode >=13. It tells you which
  85. mode you have actually been assigned on e_init with R1=1.
  86.  Bits 8-31 as follows:
  87.     b8    Set to receive RAW keyboard input. All key presses are sent
  88.         to e_char. Zap key codes greater than &FF are sent as a
  89.         zero byte followed by the low byte.
  90.     b9    Set to get taskwindow style keyboard input passed to e_chars.
  91.         This differs from normal e_chars entry in that:
  92.         1) Delete is passed on as &7F instead of calling e_delete
  93.         2) Characters &20-&FF are passed on regardless of mapping
  94.         3) If not in COPY mode then the cursor keys are passed on
  95.            as a 0 byte followed by bottom 8 bits of the wimp's code.
  96.            Similarly TAB.
  97.         4) Return and Escape are passed on as &0D and &1B.
  98.         This is subject to changes - contact me.
  99.     b10    Set to indicate that you use a mode word in a window block
  100.         (eg w_moden) to point to a block of data. See E-Windows
  101.         for the format this block must take.
  102.     b11    Set to indicate that this is not a 'textual' mode. Eg it's
  103.         like byte/word mode. Setting this bit prevents, for example,
  104.         auto DOS text file detection.
  105.     b31    Set to overwrite any mode already using this mode number.
  106.     Others bits are reserved and should be set to 0.
  107.     If b31 is not set then you are allocated the next free mode if the
  108.     one you wanted is being used.
  109.  
  110. e_init
  111. Called at various points when Zap is starting up/dying or wants to give your
  112. mode a chance to intercept an operation. Note that Zap will automatically
  113. kill your module on dying unless you tell it otherwise. You should use reason
  114. code 2 to claim any buffers from Zap. I am at liberty to add extra reason
  115. codes so please return with all registers unaltered if you receive an
  116. unrecognised code.
  117.     \E R1=reason code (and other registers may hold values dependent on it)
  118.     \X Save R1-R11 as usual unless otherwise stated below.
  119.  The reason codes are:
  120.  R1=0 => Zap is quitting and about to kill your module.
  121.      Return R0=-1 to stop this (eg if you've more than one mode).
  122.  R1=1 => Zap is just about to start up your mode (but hasn't read the
  123.       options block for this mode or anything like that).
  124.       R0=the mode number assigned to your mode.
  125.       You should note the mode number that has actually been assigned to
  126.       you and store it in your module somewhere. This is not guaranteed
  127.       to be the one you asked for.
  128.  R1=2 => Zap has started up your mode (and all other modes in your module).
  129.       You should also use this call to claim any buffers you need.
  130.      On this call you should check your mode word opt_moden to see if
  131.      it's zero. If so then you should initialise it to a sensible
  132.      default value. (See E-Vars)
  133.  R1=3 => Zap is deleting a file with your mode number in f_cmode. R9=file
  134.      block on entry. See E-File.
  135.  R1=4 => Zap is saving a file with your mode number in f_cmode. R8/R9=the
  136.      window being saved. Return R1=-1 if you wish to abort the save
  137.      (and handle it yourself). If you return R1=-1 then return R0=0 if
  138.      the save is safe (file can now be deleted) or -1 if unsafe (entered
  139.      data transfer protocol for example).
  140.      This is only called for saves to disc (F3). For inter-application
  141.      saves and post-saves see R1=8 below.
  142.  R1=5 => Zap wants to delete a file your mode number in f_cmode, but it
  143.       has the 'altered' flag set. Return R1=-1 to override and allow the
  144.       file to be killed anyway.
  145.  R1=6 => Zap is creating the colours submenu and wants to know what you
  146.       call colours >=9. Return in R1 pointer to a double zero terminated
  147.       list of zero terminated entries giving the names of the colours
  148.       starting from 9. Eg "REMs",0,"Strings",0,0. (Or leave R1 as 6
  149.       if this call is not supported).
  150.  R1=7 => Zap is creating its menus. At this point you can override your
  151.      e_menu value by returning R1 as the pointer to the replacement
  152.      (wimp-style) menu (values at #-4 and #-8 - see E-Menus).
  153.      Leave R1=7 if you don't want to do this.
  154.      You should use Zap_ReadMenu or Zap_LoadMenu to create the menu.
  155.  R1=8 => Zap is about to save a file with your mode number in f_cmode
  156.       to another application (not to disc). See also R1=4.
  157.       ;E R0=0 if the file is just about to be saved
  158.             1 if the file has been transferred
  159.          R8/R9=the file being saved
  160.  
  161. e_menu
  162. Offset of submenu in Zap's format / 0 for none. This menu comes off the
  163. 'Mode' menu. See the file E-Menu for details of the menu format. Greater
  164. versatility can be obtained by setting this to 0 and using e_init with R1=7.
  165.  
  166. e_len
  167. Total length of the table data (>=32). (So that only entry points within the
  168. table are called and for forward compatibility). If Zap finds an entry point
  169. is off the end of the table then it will call the corresponding base mode
  170. entry point.
  171.  
  172. If any of the following offsets are 0 then the corresponding offset for the
  173. basemode is called.
  174.  
  175. e_postload
  176. Called after a file is loaded and has had a window opened for it in your
  177. mode. It is also called after a file in your mode has been saved. It enables
  178. the file contents to be slightly altered before editing. (eg BASIC encrypts
  179. the line numbers and BASTXT detokenises the program). You may alter the data
  180. directly (ie, you needn't use Zap_Command).
  181.     \E R1=0 => This is a new file which has just been loaded. The window
  182.            hasn't been opened on screen yet so you can alter the file
  183.            directly.
  184.        R1=1 => File has just been saved. You should undo the effect of
  185.               e_presave. (If the effect isn't undone then the redraw
  186.               will be messed up if you don't use Zap_Command etc).
  187.        R8/R9
  188.     
  189. e_presave
  190. Called before the file is saved. It enables file contents to be slightly
  191. altered, undoing the effect of e_postload. (eg BASTXT retokenises the program
  192. prior to saving). As above, you may alter the data directly.
  193.     \E R8/R9
  194.  
  195. e_loading
  196. This is called when a file is loaded off disc for dropping into a window. The
  197. file data is in a heap block. This enables you to change it before insertion
  198. takes place (eg BASTXT detokenises the file). You are only called if the file
  199. type of the file is claimed by your mode (in the 'keys' file).
  200.     \E R2=data length R3=data address
  201.     \X You may change the data, making it larger if necessary
  202.        provided that you enlarge the heap block R3. Return
  203.        updated R2 and R3.
  204.  
  205. e_start
  206. Called when a window enters your mode (eg via Zap_NewMode). You should
  207. restore the current w_flags and w_format options, and any other options you
  208. may have saved in your private word w_moden or block pointed to by w_moden.
  209. The call Zap_RestoreModeWord should be made as this restores the options kept
  210. track of by Zap using Zap_ModeData.
  211.     \E R8/R9=window mode is being changed in OR 0 if the mode on the
  212.          options menu is being changed and you should restore the
  213.          default options, of for example opt_flags and opt_format.
  214.  
  215. e_end
  216. Called when a window leaves your mode (eg via Zap_NewMode). This is similar
  217. to e_start except that you should save the current mode dependent
  218. options from w_format, w_flags. The call Zap_SaveModeWord should be made as
  219. this saves the options kept track of by Zap using Zap_ModeData. Again, if
  220. R8=0 then this all applies to the options menu and opt_flags,opt_format.
  221.     \E R8/R9=window / 0 for iconbar menu
  222.  
  223. e_width
  224. Called when a window is (re)created to find out the width of the work area in
  225. characters (excluding margin). You should read this either from your mode
  226. word or block, or using Zap_ModeData variable number 0 where Zap reserves
  227. space for a width value for you. If you support auto width and the auto width
  228. flag is set (see E-Flags) then you should work this width out from the file.
  229. Once you have calculated the width, it is advisable to store it in w_bpl, a
  230. variable reserved for this purpose.
  231.     \E R8/R9
  232.     \X R0=width of work area in characters (excluding margin)
  233.  
  234. e_linecol
  235. Converts a column offset on screen to file offset. This is called by
  236. Zap_FindOffset and other subs. The start offset of the physical line on which
  237. the column lies has been calculated (usually by e_clnoff).
  238.     \E R0=file offset of physical line start
  239.        R1=column offset on screen (exc margin) R8/R9
  240.     \X R0=file offset of nearest character on the left
  241.         
  242. e_lineoff
  243. Convert file offset to column on screen. This performs the inverse function
  244. to e_linecol. It is usually called by Zap_OffLineCol. Again the offset of the
  245. start of the physical line has been calculated (usually by e_clnphy). This
  246. call should also return the caret width for this mode.
  247.     \E R0=file offset of physical line start
  248.        R1=file offset (to convert to a column) R8/R9
  249.     \X R0=column offset on screen (exc margin)
  250.        R1=caret width (in characters - usually 1).
  251.  
  252. The next 3 subs do the main body of work of converting between screen display
  253. lines and file offsets. A physical line means the actual offset in lines from
  254. the top of the file when displayed - that is the actual 'y' coordinate.
  255. Counting starts at 0. Logical lines can be interpreted however the mode
  256. wishes. In text mode, a logical line is ended by a return (as opposed to the
  257. display wrapping). These are given as offsets from 0 as the first line. It is
  258. important that these routines are OPTIMISED as much as possible.
  259.  
  260. e_clnlog
  261. Converts a logical line number to a file offset/physical line. This is not as
  262. important as the other two. It is mainly used by the 'GOTO' box (F5). Ie,
  263. user asks to go to logical line (eg basic line) 500 and Zap wants to know the
  264. file offset of this.
  265.     \E R0=logical line number R8/R9
  266.     \X R0=file offset of line start
  267.        R1=physical line number
  268.  
  269. e_clnphy
  270. This converts a physical line number to a file offset. This is the most
  271. important of the 3 as it is called when updating a window. For example the
  272. wimp asks zap to redraw a rectangle. The top of the rectangle is at physical
  273. line 100 say. Zap needs to know the file offset of this line to call
  274. e_redrawline. It uses this call. Do NOT start counting from the start of the
  275. file, as the window being updated may be near the end. Instead, use the start
  276. of the w_txt cache as a reference. Ie, use the variables w_cline, w_coff,
  277. w_clogl as your start reference.
  278.     \E R0=physical line number R8/R9
  279.     \X R0=file offset of line start
  280.        R1=logical line number
  281.  
  282. e_clnoff
  283. Converts a file offset to a line number and offset. This call is used by
  284. Zap_OffLineCol and when a window is first opened. It should find out which
  285. physical line a file offset lies on. If the file offset is equal to the file
  286. length then it should return the line of an 'imaginary' last character. This
  287. is called when a window is initially opened to work out the w_height value.
  288. As with e_clnphy you should use the cache reference point as a starting
  289. point.
  290.     \E R0=file offset R8/R9
  291.     \X R0=physical line number
  292.        R1=file offset of physical line start
  293.        R2=logical line number
  294.  
  295. e_nextline
  296. This is called during a Zap_DoCommand operation. It is designed to work out
  297. the first line on screen which can be shifted down, following an insertion/
  298. deletion, without being redrawn. On entry you are told the first character
  299. which occurs after the altered region and the amount by which its offset will
  300. change due to the alteration. You must return the file offset of the first
  301. line which may be shifted on the screen without being redrawn. (Usually the
  302. first logical line with start offset > R0). In the case where there is no
  303. such line, return the end of file offset and the physical line containing
  304. this 'imaginary' character offset (as for e_clnoff).
  305.  See also e_prevline. e_prevline is called first, and the file block is
  306. set up as for e_prevline.
  307.     \E R0=file offset of first 'shiftable' character
  308.        R1=signed change in file offset of this character R8/R9
  309.     \X R0=file offset of first 'shiftable' line
  310.        R1=physical line number of this line #
  311.        You must preserve the split offset and split size of the file.
  312.        
  313. e_minus
  314. This is called when the user presses the left arrow key to work out the next
  315. cursor position. The buffering is done for you.
  316.     \E R0=physical line start file offset
  317.        R1=cursor file offset
  318.        R2=cursor column (exc margin) R8/R9
  319.        R10=cursor caret block
  320.     \X If R2>=0 then R1,R2 given new cursor position on the
  321.        same physical line.
  322.        If R2=-1 then R1=new file offset of cursor.
  323.        If R2=-2 then you have moved the cursor yourself.
  324.        If R2=-3 then R0,R1=new x,y for cursor.
  325.  
  326. e_plus        Perform cursor right (\E & \X as for e_minus)
  327. e_sminus    Perform cursor back a word (\E & \X as for e_minus)
  328. e_splus        Perform cursor forward a word (\E & \X as for e_minus)
  329. e_cminus    Move cursor to line start (\E & \X as for e_minus)
  330. e_cplus        Move cursor to line end (\E & \X as for e_minus)
  331.  
  332. e_redrawline
  333. This is called when your mode is required to redraw one (physical) line of
  334. the display - it is also here that you can specify the colour of each
  335. character. You are passed:
  336.  1) As input:
  337.     The physical line start (calculated via e_clnphy - or the previous call
  338.     to this sub). This is not passed as a file offset, but as an actual
  339.     ADDRESS in the file buffer (in R7). Recalling the split nature of the
  340.     buffer (see E-File) the text may not be continuous. R10 is set to the
  341.     end of this section of the split so the file is continuous up to R10.
  342.     R5=R7-the offset of the character - I call this the apparent buffer start
  343.     (where the start would be if the file were continuous).
  344.  2) For output:
  345.     The address of a buffer (in R6) in which to write the characters to
  346.     appear on the line (one byte per character). This buffer has been
  347.     cleared to spaces beforehand so you only need to write the non-space
  348.     characters. Line numbers have been dealt with. You told Zap the width
  349.     the buffer should be when your e_width entry point was called.
  350.  3) Colours:
  351.     As far as this call is concerned there are up to 256 colours (numbered
  352.     0-255) available. Numbers 0-8 have a standard meaning and 9+ can be
  353.     declared for use by the mode (see e_init with R1=6/Zap_ModeColourNum).
  354.     These colour numbers bear no resemblance to wimp colour numbers, but are
  355.     'internal' Zap colour numbers. Their actual physical appearance is chosen
  356.     by the user from the colours menu - and can be selected from a
  357.     palette. Colours 0-8 have a standard interpretation but colours 9+
  358.     can be used as the mode sees fit. Eg, colour 9 may be used for IF
  359.     statements in a language editor for example. The standard colours are
  360.         0=Background colour 1 (default background colour + off end of text)
  361.         1=Background colour 2 (this should be used under text)
  362.         2=Standard foreground colour
  363.         3/4=selection bac/foreground 5/6=cursor bac/foreground
  364.         7=line numbers 8=control characters.
  365.     Let n be the value stored in [R8,#w_txtw]. Then the foreground colour of
  366.     the cached character stored at R6 is stored at R6+n and the background
  367.     colour at R6+2*n. These are initially cleared to bytes '2' and '0'
  368.     respectively - you should overwrite these bytes to change the colour.
  369.     Text mode puts colour 1 (background colour 2) under actual text and you
  370.     should do the same. See e_init for how to change the colours menu.
  371.  4) Other comments:
  372.     On exit you should update several registers to the start of the next
  373.     physical line. e_clnphy is only called for the first line in a group.
  374.     For a simple example of how to write this redraw code, see the code for
  375.     mode 3 (ascii mode).
  376.     \E R4=w_format (read from R8,#w_format)
  377.        R5=apparent buffer start (R7-offset of char in file)
  378.           (so it is either f_ptr or f_ptr+f_splits)
  379.        R6=address of cache line to draw line in (already blanked)
  380.        R7=address of start of (source) line (R5+file offset of line).
  381.        R8/R9
  382.        R10=address of end of this section of the buffer.
  383.            (so when you reach R10 you increase R5 and R7 by f_splits if
  384.            at the end of the first half or stop if at the file end).
  385.        R11=logical line number (for you to update for cache reference
  386.            and printing in the left hand column).
  387.     \X R0-R4,R6,R10 may be corrupted
  388.        R5,R7,R11 must be updated to the start of the next physical line
  389.        R8-R9,R12 must be preserved
  390.  
  391. e_redrawlnum
  392. This is called when the user wishes logical line numbers to be displayed on
  393. the left. You must decide whether the given physical line file offset it at
  394. the start of a logical line. This is called while redrawing the line numbers.
  395.     \E R7=file offset of start of physical line
  396.        R11=proposed logical line number (as calculated by e_clnphy)
  397.        R8/R9
  398.     \X CC if R7 is at the start of a logical line (so print it)
  399.        CS if the line number column should be left blank
  400.        You may corrupt R0-R4. You may also change R11 as BASIC does
  401.        but this is not advised as the w_clogl will get out of sync.
  402.        BASIC ignores the w_clogl as the line number is stored in the
  403.        file.
  404.  
  405. e_char
  406. This is called when the user types a string of ascii chars via the CHAR
  407. command. The characters have been concatenated for you. You should perform
  408. the relevant insertions/deletions via Zap_Command.
  409.     \E R4=w_flags
  410.        R5=number of bytes typed
  411.        R6=w_format
  412.        R7=address of typed data
  413.        R8-R10=input caret (ie this points to the block car_cursor or
  414.               car_input depending on the caret mode and where typed
  415.               text should go).
  416.     \X You may corrupt R0-R11
  417.  
  418. e_delete
  419. This is called when the user executes the commands DELETE or DELETENEXT. A
  420. sequence of deletes is concatenated for you. You should use Zap_Command to
  421. delete the text. Try and support the line edit mode.
  422.     \E R5=number of times pressed
  423.        R6=w_format
  424.        R7=0 for DELETE/1 for DELETENEXT
  425.        R8-R10=input caret
  426.     \X You may corrupt R0-R11
  427.  
  428. e_tab
  429. This is called when the user executes the command TAB. As usual, repetitions
  430. are concatenated. Use Zap_Command to perform the function.
  431.     \E R1=number of times pressed
  432.        R8-R10=input caret
  433.     \X You may corrupt R0-R11
  434.  
  435. e_return    Called when RETURN executed (\E \X as for e_tab)
  436. You should insert an appropriate number of newlines - remember to take
  437. account of the buffering in R1.
  438.  
  439. e_renumber    Called when RENUMBER executed (\E \X as for e_tab)
  440. You should renumber/restyle the program - language specific.
  441.  
  442. e_saveandrun    Called when SAVEANDRUN executed (\E \X as for e_tab)
  443. You should save the program and then run it so that the program quits when
  444. finished. This will often duplicate e_compile.
  445.  
  446. The next 4 subs are used by the various delete line calls. They each have
  447.     \E R0=current file offset in a line R8/R9
  448.     \X R0=new file offset (see below)
  449. This is how the subs are called:
  450.  
  451. DELLINE        Deletes from lineprev to linenext offsets.
  452. DELTOEND    Deletes from current offset to lineend unless this is empty
  453.         when it calls JOINLINE (as in emacs ctrl K)
  454. DELTOSTART    Deletes from linestart to current offset unless empty.
  455.  
  456. e_linestart    Called to find the lines first character.
  457. e_lineend    Called to find the lines last character.
  458. e_linenext    Called to find the lines actual end (eg after &0A)
  459. e_lineprev    Called to find the lines actual start (eg for basic lines)
  460.  
  461. e_copy
  462. Called when user wishes to copy characters via the COPY key. Is is called for
  463. finding the characters to copy and for inserting the copied characters.
  464. Reason code is in R0. When reading characters you must update the cursor
  465. yourself. Note the source window may be in a different mode to the
  466. destination window!
  467.         \E R0=1 => Fetch characters
  468.            R1=number of times copy pressed (number of chars to get)
  469.            R8-R10=copy cursor (car_cursor)
  470.         \X R3=pointer to buffer containing characters to 'type'
  471.            R2=number of characters to 'type'
  472.            Copy cursor updated to new position
  473.         OR
  474.         \E R0=2 => Write copied characters
  475.            R2=number of chars to type
  476.            R3=pointer to the chars
  477.            R8-R10=input cursor (car_input)
  478.         \X R0=0 means you've done it all yourself
  479.            R0=1 means please enter it for me via Zap_Command
  480.            R0=2 means please enter it for me by calling my e_chars
  481.  
  482. e_joinline    This is called when Joinline pressed (\E \X as for e_tab)
  483. e_splitline    This is called when Splitline pressed (\E \X as for e_tab)
  484.  
  485. e_aligncaret
  486. This is called before any commands are executed on a window in your mode.
  487. It serves two purposes. The first is to align the input caret offset to a
  488. sensible position (eg word align in word mode, put after line numbers in
  489. basic). The second is to reset any counters you may have. For example, the
  490. hex mode entry uses a counter to tell how many nibbles have been inserted in
  491. a word. This is cleared on e_aligncaret with the old value being saved. Then
  492. if the command 'insert 9' is executed it can retrieve and restore the saved
  493. value. If any other command is executed (eg LEFT) then the counter will
  494. remain reset.
  495.     \E R8-R10=caret
  496.     \X Input caret offset [R10,#c_off] can be updated.
  497.  
  498. e_command
  499. This entry point is called whenever anyone issues a Zap_Command call, or
  500. equivalent, to try and alter a file in a window in your mode. The easiest way
  501. to deal with this is to pass the call onto Zap_DoCommand which will perform
  502. the alteration. However, if you support wordwrap, you may wish to 'fiddle'
  503. the data, or even perform additional operations.
  504.     \E As for Zap_Command
  505.  
  506. e_compile    This is called when Compile pressed    (\E \X as for e_tab)
  507. The mode should save the file to disc and then try to compile/run it.
  508.  
  509. e_formattext    This is called when Formattext pressed    (\E \X as for e_tab)
  510. The mode should try and format the current paragraph for its particular
  511. language.
  512.  
  513. e_run        This is called when Run pressed        (\E \X as for e_tab)
  514. The mode should try and run the program without saving it. Revert to
  515. e_compile code if there is no difference.
  516.  
  517. e_runandquit    This is called when Runandquit pressed    (\E \X as for e_tab)
  518. This should act as e_run but add a -quit option if possible.
  519.  
  520. e_basic        This is called when Basic pressed    (\E \X as for e_tab)
  521. This should drop the file into the command line state of the current
  522. language.
  523.  
  524. e_search
  525. This handles string searches in your mode. When the 'Raw search' option is on
  526. the file is searched directly and the mode has no control over it. When, as
  527. usual, the option is off the the text is searched through in lines. Each mode
  528. has a chance to turn a line of the file into meaningful text. For example,
  529. BASIC mode will detokenise the line and Code mode will disassemble the
  530. instruction. Unrecognised reason codes should be ignored (and registers
  531. preserved). After the line has been searched you are called again to convert
  532. a match to a file offset and/or specify the start/end of the next line to
  533. search (depending on the search direction).
  534.     \E R1=reason code
  535.           0 = starting a search - now obsolete and no longer used.
  536.           1 = match found - now obsolete and no longer used.
  537.           2 = starting search in a line (non 'raw' search)
  538.               Then R3=file offset of current search position
  539.                    R4=search direction (+1/-1)
  540.                    R8/R9=the window being searched
  541.               \X Preserve R1+ to use the standard text search routine
  542.                  or set R1=pointer to 'detokenised line' string.
  543.                 R2=offset in the string of the search posn.
  544.                 R3=file offset of the start of the line.
  545.                 R10=length of the string pointed to by R1.
  546.           3 = has finished searching through this line. You are called
  547.               with:
  548.            R1=pointer to 'detokenised string'
  549.            R2=offset in the string of the match/-ve if not found
  550.            R3=offset in the file of the start of the line
  551.            R4=search direction (+1/-1)
  552.            R8/R9=the window being searched
  553.            R10=length of the line
  554.           \X Preserve registers for default action. Otherwise
  555.           if a match has been found (R2 +ve) then you should set
  556.            R1=0
  557.            R2=file offset of the match
  558.            R3=next file offset to look at (usually R2+R4)
  559.           if a match was not found you should set
  560.            R1=0
  561.            R2=-ve (ie preserve it)
  562.            R3=next file offset to look at (usually R3+R10 or R3-1)
  563.           the search will be aborted (or move onto the next file if
  564.           R3<0 or R3>=file length).
  565.           4 = has found a match and wants to know the file offset of the
  566.               end of the match. This is called before the call with R1=3
  567.               to find the start. You are called with registers as set
  568.               up for R1=3 except R2=offset in the string of match end.
  569.               \X As for R1=3 except R2=file offset of end of match
  570.               and R3 is not used (you may corrupt it).
  571.               [Usually you will call the same code for R1=3 or 4]
  572.           5+ = reserved
  573.  
  574. e_replace
  575. This is called when the user wishes to perform a search and replace. The
  576. replacement string has been calculated for you and it is your job to insert
  577. it. Your default action should be to call Zap_ReplaceArea.
  578.     \E R1=file offset (of match)
  579.        R2=length (of match)
  580.        R3=replacement data
  581.        R4=replacement length. R8/R9
  582.  
  583. e_selection
  584. This handles region selections/saving. You should check the validity of the
  585. selected area, confining it to lines/paragraphs if you wish.
  586.     \E R0=reason code R8/R9=window
  587.        R0=0 => starting selection
  588.            R10=proposed start caret. You can use the variable car_mode
  589.            to find out if the selection is mouse or keyboard (E-Vars).
  590.        R0=1 => updating selection size
  591.            R10=new selection block (car_selection)
  592.             You may alter the contents of the selection block.
  593.        R0=2 => saving selection
  594.            R3=data address (a heap block)
  595.            R2=data len
  596.                R4=proposed filetype
  597.             You may change these provided R3 remains a heap block.
  598.             (eg BASIC will tokenise it).
  599.  
  600. e_click
  601. This is called when the user clicks on your window. Default action should be
  602. to call Zap_DefaultClick which will handle R1=0,1 and ignore the rest. Clicks
  603. are registered to any depth so you should modulo the click number with the
  604. number of useful actions you support so they cycle round. Drags are also
  605. passed to you. If the user drags straight away (ie after 1 click) then you
  606. will be sent R1=0. If the user drags after a double click then you will
  607. be sent R1=2 and b3 of R4 will be set. After treble click R1=3 etc.
  608.     \E R1=click depth (0=simple drag 1=single click 2=double click etc)
  609.        R2=x column (including margin)
  610.        R3=y row of click in work area characters
  611.        R4=buttons   b0=adjust pressed
  612.                b1=undefined (menus are dealt with by Zap)
  613.                b2=select pressed
  614.                b3=drag after two or more clicks (given in R1)
  615.                b4-b31=reserved
  616.        R8/R9=window clicked on
  617.  
  618. e_message
  619. This entry point is called when an unrecognised wimp message is received by
  620. Zap. The message is broadcast to all modes. Please IGNORE (ie return) unless
  621. you understand the message number and the window handle!!
  622.     \E R0=your mode number
  623.        R1=message block (as sent by wimp)
  624.        R2=R1!16=message number if R3=17 or 19
  625.        R3=message type
  626.           (Null requests are scheduled - use Zap_CallBack)
  627.           1=redraw window request for unrecognised window
  628.           2=open window request for unrecognised window
  629.           3=close window request for unrecognised window
  630.           4=pointer leaving unrecognised window
  631.           5=pointer entering unrecognised window
  632.           6=mouse click on unrecognised window
  633.           (Drags dealt with by Zap - use Zap_DragBox)
  634.           8=key press for unrecognised window
  635.           (Menu clicks handled automatically - use Zap_OpenMenu)
  636.           10=scroll request for unrecognised window
  637.           11=lose caret for unrecognised window
  638.           12=gain caret for unrecognised window
  639.           13-16=passed straight on (not recognised by Zap)
  640.           17=unrecognised user message (or recognised message applying
  641.              to unrecognised window)
  642.           (type 18 gets passed on as 17 as well)
  643.           19=unrecognised bounced message
  644.           20+=passed straight on (not recognised by Zap)
  645.  
  646. e_setwidth
  647. This entry point is used by the SETWIDTH command (Ctrl W) and the 'width'
  648. menu option on the display menu. It is called to read the currently
  649. configured width for this mode (of a window or the default according to R8),
  650. or in order to set the currently configured width. You should access this
  651. width by looking at your mode word w_moden if that's where you keep it, or
  652. using Zap_ModeData if you keep it in the place provided by Zap (this is the
  653. default action of the text mode entry point). Following this call, the editor
  654. window in question will be recreated automatically and your e_width entry
  655. point will be called to calculate the actual display width as usual.
  656.     \E R0=new width user wants or -1 to read the current width
  657.        R8-R9=window/0 if it is the default width being changed.
  658.     \X R0=current width if it was -1 on entry.
  659.  
  660. e_listfns
  661. This is called when the command LISTFNS is pressed. \E \X as for e_tab. The
  662. mode should open a throwback buffer with a list of function definitions in.
  663. (eg Use Zap_Search).
  664.  
  665. e_prevline
  666. This entry point is used in conjunction with e_nextline to find the area on
  667. the screen which needs to be updated after an insertion/deletion. It tells
  668. you in R0 the first file offset being changed and you must tell it the first
  669. file offset (<=R0) to start updating the screen from. Usually you will just
  670. leave R0 unchanged but in the case of a mode using colours - where changing a
  671. character later on in the line may affect earlier colours - you may want to
  672. set this to the start of the current logical line. The cache reference point
  673. (w_cline/w_coff) is moved so that it is most R0, and is thus not corrupted by
  674. the insertion/deletion. If you wish to move it further back (eg if a control
  675. code later in a line effects the formatting of earlier bits) then now is the
  676. time to do so - via Zap_ClipCache.
  677.  e_prevline is called before e_nextline. Complicated colouring modes (eg
  678. colour C mode) need to know what data is being inserted/deleted to decide
  679. what to return for e_prevline/e_nextline. To make this possible, the
  680. following data is available:
  681.  f_docom=the command currently being executed:
  682.  0,>5=none   => text not changing (just return with R0 preserved).
  683.  1=insertion => R0=offset that text is being inserted at
  684.          f_dolen=number of characters being inserted
  685.          f_dodata=pointer to the text being inserted
  686.          File is split at the offset R0 with split size >= f_dolen.
  687.  2=deletion  => R0=offset of start of block to delete
  688.          f_dolen=number of characters being deleted
  689.          File is split at R0+f_dolen with split size >=0.
  690.  3/4=replace => R0=offset of start of block to replace
  691.          f_dolen=number of characters to replace
  692.          f_dodata=replacement block
  693.          File is split at R0+f_dolen with split size >= f_dolen.
  694.     \E R0=First changed offset in the file. R8/R9
  695.     \X R0=Offset to start updating the screen from.
  696.        You must preserve the split offset and split size of the file.
  697.  
  698. e_openwindow
  699. This entry point is for the use of modes which want to provide panes on the
  700. main Zap window. It tells you when the window is being resized (but not
  701. scrolled)
  702.     ;E R0=0 => Just before calling Wimp_OpenWindow
  703.        R0=1 => Just after calling Wimp_OpenWindow
  704.        R0>1 => Reserved.
  705.        R1 = Open block (as for Wimp_OpenWindow) (may have R1=R8)
  706.        R8 = Zap window block
  707.     ;X Preserve R1+ as usual. VS on error etc.
  708.